OUBLIETTE - LANGUAGE PACKS
updated: 06 May 2003
--------------------------

To display the program in another language, you need to download and install a language pack. You can also create a language pack and prepare the translation yourself: please see below for details on how to do that.

Language packs will be available in the "Downloads" section for each application, at www.tranglos.com.

The current set of language packs for Oubliette will be available as:
http://www.tranglos.com/free/files/oub_langpack.zip

--------------------------

WHAT ARE LANGUAGE PACKS?

This subdirectory holds language packs: files used to display the program in other languages. The "Locale" folder should be a subdirectory under the folder where the program is installed. For example, if the program is installed in
	C:\Program Files\Oubliette
then language packs should be unzipped into
	C:\Program Files\Oubliette\Locale

The folder structure of language packs is:
Locale\application_name\LANG_CODE

(where application_name is "oubliette")

LANG_CODE is an ISO language code for language and variant, e.g. en_UK for British English, en_US for US English, etc.

Each LANG_CODE subfolder holds a set of files for one language (currently, each set consists of two files: forms.loc and messages.loc). These folder and files should not be moved or renamed.

--------------------------

HOW TO USE LANGUAGE PACKS?

To display the program in another language:
1. Choose Tools menu, "Select language".
2. Select the language pack you want to use.
3. Check the "Use selected language pack" option.
4. Click OK.

To stop using a language pack:
1. Choose Tools menu, "Select language".
2. Uncheck the "Use selected language pack" option.
3. Click OK.
4. Restart the program.

To load a different language pack:
1. Choose Tools menu, "Select language".
2. Select the language pack you want to use.
3. Click OK.

Additional language packs will be made available
as soon as translations start to arrive. If you
would like to translate the program, please read
the section below.

--------------------------

HOW TO TRANSLATE THE PROGRAM?

To create a new language pack for translation:

1. If the program is running, close it.
2. Start the program with the following commandline
   arguments: /loc /nolang

     /nolang tells the program NOT to load a language
   pack if you are using one. (It has no meaning
   if you are not using any language pack)

     /loc tells the program to store all its messages
   for translation.

For example, click the Start button, select "Run...",
enter the following command and then click OK:
c:\program files\oubliette\oubliette.exe /loc /nolang

3. The program will start and display a dialog box.
   In  this dialog box, select the language into which
   you will be translating the program. The language
   determines the folder in which the language pack
   will be stored (the folder must not be renamed).

Translatable resources will be stored in two files:
a) messages.loc - runtime messages
b) forms.loc - dialog box resources

The two options displayed under the language selector
control whether one or both of these files will be stored.
Note that both files MUST be present in order for the program
to load the language pack, but you can choose to create
only one, for example if the other one already exists.

4. If you are creating a new translation, UNCHECK the "Preserve
existing translation" option.

If you already have an existing translation and want to
update it (for example, because a new version of the program
has been released and there are a few new messages to be
translated), CHECK the "Preserve existing translation" option.

5. Click OK.

The files will be stored under the Locale subdirectory,
according to the folder structure described above.

Translate the files.

--------------------------
TRANSLATING THE LANGUAGE PACK FILES

The files have a simple INI-like structure:

[secton name]
identifier="Text to translate"

The identifiers must not be changed (they are CASE-SENSIIVE,
for faster access when loading a translation). The leading
and trailing quotes should not be removed.

Translatable text may sometimes contain the following
metacharacters:

\n - denotes a linebreak
\t - denotes a tabulator

These metacharacters should not be changed.

Other things to watch for:
a) do NOT change section names in any way.
b) do NOT translate or change text in any
   section whose name ends with an exclamation
   point. For example, the file forms.loc may
   have a section like the following:

[TForm_Main.COLLECTIONSECTIONS!]
StatusBar.Panels="TForm_Main.StatusBar.Panels"

Do not change ANYTHING in these sections.

Both .loc files have a [Loc.TranslatorInfo] section on top. Please enter appropriate information in this section: your name, your email address, and an optional URL address and comment. The email address is useful if someone wants to contact you regarding the translation.

Do not change anything in the section called [Loc.FileInfo]. This section is used for information purposes only, but eventually it will be used to ensure compatibility across different versions of the localization mechanism built into the program.

When you have finished translating the files, you may email them to me, if you wish (marek@tranglos.com), so that I can include them in the program distribution and make available to other users. Alternatively, you can post them on your own website and only email the URL to me, so that I can post a link to your site.

--------------------------
TESTING A LANGUAGE PACK

Testing is not as convenient as it could be - this will be improved eventually. First, follow the steps outlined in "How To Use Language Packs".

If you are editing the forms.loc file, you can test your changes by simply reopening any dialog box. however, if you change the translation of the main main program window, you need to restart the program, or change the language pack.

If you are editing the messages.loc file, you also need to restart the program or change the language pack.

This is the first release of a program using the localization engine I developed, so please treat it as BETA. There may be bugs. If you encounter a problem or want to ask a question or suggest an improvement, please do not email me directly - instead, post a message in the "Localization" forum at http://forum.tranglos.com. This way other translators will receive what is potentially important information, and I won't have to retype the same emails over and over :)

Programmers: the localization engine is released as part of my base library for Delphi 5 and higher. This is an ongoing, often updated package, distributed under Mozilla Public License 1.1. The library is available at http://www.tranglos.com/free/files/gf_lib.zip.


--------------------------
LIMITATIONS

1. No support for Unicode or DBCS. No such support is planned.

2. The process of storing program messages for translation cannot be performed on Windows 95. You can display the translated messages on any version of Windows, but you will not be able to create language packs for translation on Windows 95. In that case, you can use the language pack stored in the en_US folder, which is the original set of messages.

3. A translated application can still display some messages (esp. error messages) in English. If you have an English version of Windows, all system error messages will be in English, because they come from Windows, not from the application itself. Similarly, on an English version of Windows, message dialog boxes will have English captions ('Information', 'Confirmation', 'Error', etc.) and English buttons ('OK', 'Cancel', etc.).

Certain other messages may also be displayed in English if they come from third-party components used in the application. This could be helped, but it would require changing some of the source code in third-party components, which is not a feasible option if the components are still under development (I would have to repeat the whole procedure manually every time the component is replaced with a newer version).



--------------------------
Marek Jedlinski
marek@tranglos.com
http://www.tranglos.com
